# @v-uik/showroom

Пакет-витрина всех компонентов библиотеки.

## Как писать документацию для компонента

Создаем папку с именем компонента в пакете `showroom/Button`.

Далее, необходимо создать файл с именем `story.mdx`. Как работать с [MDX форматом](https://storybook.js.org/docs/react/writing-docs/mdx)

В файле будет всего одна история, которую пользователь сможет изменить с помощью блока `ArgsTable`. Давайте разберем каждый этап.

Для начала делаем импорт всех зависимостей, которые будут использоваться в нашей истории.

```md
import { Meta, Story, Canvas, ArgsTable } from "@storybook/addon-docs"
import { Button } from "@v-uik/button"
```

Далее нужно добавить имя истории. Будет основная история, которую пользователь сможет настраивать с помощью блока `ArgsTable`. Чтобы все истории находились в меню в одной категории `Components`, необходимо в заголовке и истории указать одинаковые имена. Подробнее на странице [документации](https://storybook.js.org/docs/react/writing-stories/naming-components-and-hierarchy#single-story-hoisting).

```mdx
import { Meta, Story, Canvas, ArgsTable } from '@storybook/addon-docs'
import { Button } from '@v-uik/button'

<Meta title="Components/Button" component={Button} />

<Story
  name="Button"
  parameters={{ docs: { disable: true } }}
  args={{ children: 'Button' }}
>
  {(args) => <Button {...args} />}
</Story>
```

Обратите внимание, что компонент обернут в функцию и пробрасывается параметр `args`, а также имеется одноименное свойство компонента `Story`. Это необходимо для корректной работы `ArgsTable`. Подробнее про эту функциональность можно прочитать на странице [документации](https://storybook.js.org/docs/react/writing-docs/doc-blocks#argstable).

Далее идет шапка истории — заголовок, описание, подключение таблицы свойств `ArgsTable` и пример импорта. Хорошее описание помогает быстро разобраться пользователю, в каких случаях следует использовать этот компонент. Попробуйте придумать описание самостоятельно или обратиться за помощью к коллегам. Также в этом вопросе могут помочь готовые библиотеки компонентов, например [Material UI](https://material-ui.com/ru/components/buttons/#button) — попробовать заимствовать некоторые формулировки и примеры из них.

````
# Button

Кнопки позволяют пользователям выполнять действия и делать выбор одним нажатием.

<ArgsTable of={Button} />

## import

// Следующий блок необходимо обернуть в ``` чтобы отображался как блок кода, который удобно копировать.
import { Button } from '@v-uik/Button'
````

Далее идет набор полезных примеров, с которыми может встретиться пользователь при работе с вашим компонентом. Примеры лучше позволяют понять где и как использовать этот компонент. Для каждого примера также можно давать описание, чтобы пользователь мог лучше разобрать отдельные случаи.

```mdx
## Заполненные кнопки (default)

Данный тип кнопок имеет высокий акцент/

<Canvas>
  <Button>Primary</Button>
  <Button color="secondary">Secondary</Button>
  <Button color="error">Error</Button>
</Canvas>
```

В примере мы хотим увидеть результат и необходимый набор параметров для компонента, которые пользователь может быстро скопировать и использовать в своем проекте. Методом проб и ошибок, пример выше является самым удачным — компонент `Canvas` копирует содержимое в блок `source` как есть.

Если вы хотите представить более сложный пример, который будет содержать не только верстку, вы можете вынести это в отдельный файл и подключить как компонент. В этом случае для корректного отображения `source`, лучше продублировать в блок `Code`.

SomeComponent.tsx

```tsx
import { SomeStory } from './SomeStory'
import RawSomeStory from '!!raw-loader!./SomeStory'

<Canvas withSource="none">
  <SomeStory />
</Canvas>

<Source language="tsx" code={RawBasic} />
```

Если вы найдете более подходящий вариант, не стесняйтесь сделать PR =)

## Отображение типов и интерфейсов с помощью компонента ArgsTable

Иногда возникает необходимость описания в документации вспомогательных интерфейсов (например тип Option для компонента Select и т.п.).
Для однородности содержимого документации рекомендуется использовать компонент сторибука ArgsTable, но он принимает только react-компоненты,
поэтому создаем компонент-пустышку с суффиксом `.dummy.tsx` (это условие обязательно, так как кодогенератор настроен обрабатывать файлы только с такими именами), и в качестве типа свойств компонента вставляем необходимый нам интерфейс.

```tsx
import * as React from 'react'
import { Option } from '@v-uik/select'

export const OptionDummy: React.FC<Option> = () => null
```

и в файле документации (.mdx) вставляем

```mdxjs
import { OptionDummy } from './Option.dummy'
...
<ArgsTable of={OptionDummy} />
```
